home *** CD-ROM | disk | FTP | other *** search
/ Collection of Internet / Collection of Internet.iso / winprogs / wlprs40a / wlpr2.asc < prev    next >
Encoding:
Text File  |  1994-05-27  |  12.4 KB  |  312 lines
  1.                                                            
  2.                                                           1
  3.                              
  4.                              
  5.                              
  6.                              
  7.                              
  8.                              
  9.                              
  10.                              
  11.                              
  12.                              
  13.                              
  14.                              
  15.                          WLPR2.DLL
  16.                        Version 2.0a
  17.                              
  18.                              
  19.                        User's Guide
  20.                              
  21.                              
  22.                        May 27, 1994
  23.                              
  24.                              
  25.                              
  26.                              
  27.                              
  28.                              
  29.                              
  30.                         Thomas Heil
  31. This  document was created with Microsoft Word for  Windows
  32. 2.0
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39. DISCLAIMER:
  40.  
  41. THE  SOFTWARE  IS PROVIDED AS-IS. THE AUTHOR DISCLAIMS  ALL
  42. WARRANTIES,  EITHER EXPRESS OR IMPLIED, INCLUDING  BUT  NOT
  43. LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS
  44. FOR  A  PARTICULAR  PURPOSE. NO LIABILITY  IS  ASSUMED  FOR
  45. DAMAGES, DIRECT OR CONSEQUENTIAL, WHICH MAY RESULT FROM THE
  46. USE OF THIS SOFTWARE.
  47.  
  48. (C) Copyright 1992-94 by Thomas Heil.
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59. All  trademarks appearing in this document are the property
  60. of their respective owners.
  61.  
  62.  
  63. Table of Contents
  64.  
  65. Table of Contents                                         3
  66. Introduction                                              5
  67. Copyright:                                                5
  68. Author:                                                   5
  69. New Features in Version 2.0                               6
  70. Setting Properties for Remote Queues                      6
  71. DLL Settings                                              8
  72.     Section Miscellaneous:                                 8
  73.     Section Timeouts:                                      8
  74. Known problems:                                           8
  75. Troubleshooting:                                          9
  76. Change Log:                                               9
  77.  
  78.  
  79. Introduction
  80.  
  81. WLPR2.DLL  contains a set of API functions  that  allow  an
  82. application  to  print  to  remote  printers,  query  their
  83. queues,  and  remove  print jobs from their  queues.  These
  84. printers  must  understand the LPR/LPD  protocol  which  is
  85. defined  in RFC 1179. An application  that calls  this  DLL
  86. does   not   need   to   have  any  knowledge   about   the
  87. implementation details. It may call functions in  this  DLL
  88. to  set/modify  properties for individual queues,  such  as
  89. number  of copies to print, whether a banner page shall  be
  90. generated, etc.
  91.  
  92.  
  93. Copyright:
  94.  
  95. This   DLL  is  Copyright  (C)  1993-94  by  Thomas   Heil.
  96. Redistribution  of this DLL is allowed only  together  with
  97. the  documentation  (as PostScript .PS file  and  as  plain
  98. ASCII  .ASC file). This software may not be sold by itself.
  99. Applications  that use this DLL may be sold  together  with
  100. the DLL and its documentation included royalty free.
  101.  
  102. If  you  want  to  write a similar DLL that implements  the
  103. WLPR2 API for another protocol, please feel free to contact
  104. me for implementation details.
  105.  
  106.  
  107. Author:
  108.  
  109. Thomas Heil
  110. Hindenburgstr. 50
  111. 41352 Korschenbroich
  112. E-Mail: th.heil@kfa-juelich.de (Internet)
  113.  
  114. Phone: +49 2161 644895
  115. Fax: +49 2161 644337
  116.  
  117.  
  118. New Features in Version 2.0
  119.  
  120. The DLL was totally restructured. Now all protocol relevant
  121. stuff is totally included in the DLL. E.g. with version 1.x
  122. an  application had to have an own dialog for  setting  the
  123. queue properties. Now that is all handled by the DLL itself
  124. which  exports  an  appropriate function.  This  makes  the
  125. calling   application  independant  of  the  implementation
  126. specifics of the transport protocol, and allows it  to  use
  127. several  different Protocol DLLs that offer the  WLPR2  API
  128. side by side.
  129.  
  130. This DLL is not compatible with WLPR.DLL Version 1.x.
  131.  
  132.  
  133. Setting Properties for Remote Queues
  134.  
  135. If   your   application  allows  you  to  view/change   the
  136. properties  of a remote queue, you get a dialog that  looks
  137. like this:
  138.  
  139.  
  140.  
  141. In this dialog, the following settings can be made:
  142.  
  143. Send     header If  checked,  a header page is generated  with
  144. page:           each  print  job.  If not checked,  no  header
  145.                 page  is  printed.  Note that  this  might  be
  146.                 overridden  by  the  settings  of  the  remote
  147.                 print server (default: on).
  148. Copies:         Set  the  number of copies that  a  print  job
  149.                 generates (default: 1).
  150. Class:          Sets  the job class of print jobs that  go  to
  151.                 this   queue.   This  class  name   might   be
  152.                 interpreted by the print server in  some  way.
  153.                 Check    with   your   local   print    server
  154.                 administration  for  classes  that  have  some
  155.                 relevance (default: none).
  156. CRLF->LF        Normally,  files  going to  a  queue  of  type
  157. conversion      "Formatted  File  (f)" and  "Print  with  'pr'
  158.                 (p)"  run  through  a filter  that  translates
  159.                 CRLF  sequences to single LineFeeds. This  can
  160.                 be  switched off with this check box (default:
  161.                 Filtering is on).
  162. File Type:      The  given file types are those that RFC  1179
  163.                 defines,  although  normally  just   a   small
  164.                 subset  is really needed. The problem is  that
  165.                 not  every  server accepts all types,  so  you
  166.                 might  have  to try a bit around.  You  should
  167.                 take  the  following approach:  If  PostScript
  168.                 files  or plain ASCII files are sent  to  this
  169.                 queue, you should select "Formatted File".  If
  170.                 you  send  binary  printer data  (e.g.  output
  171.                 from  a Windows printer driver) to this queue,
  172.                 you  should select "Raw Print File". Note that
  173.                 the type "Postscript File" is not accepted  by
  174.                 a lot of LPD implementations.
  175.                 Plain  ASCII files can also be sent  with  the
  176.                 setting   "Print  with  'pr'".  This  normally
  177.                 means  that  the  file is  sent  through  some
  178.                 formatting  filter on the print  server  which
  179.                 allows  header  lines to  be  written  on  the
  180.                 output.  If  you  select  this  type  you  can
  181.                 specify  the  desired  page  header  line   as
  182.                 "Document  Title", and also modify margin  and
  183.                 line width settings.
  184.                 If  you  select TROFF/DITROFF output  you  can
  185.                 specify which fonts shall be used for output.
  186.                 The  file  types "Formatted File"  and  "Print
  187.                 with  'pr'"  cause  the  print  file  to   run
  188.                 through     a     filter     that     converts
  189.                 CarriageReturn/LineFeed sequences to a  single
  190.                 LineFeed.
  191. Long query      If  checked,  the  user gets  a  more  verbose
  192.                 listing   when  querying  the  remote   queue.
  193.                 Otherwise he gets a standard listing.
  194.  
  195. When  the dialog contains just an "Ok" button, the settings
  196. are  saved  when  this button is pressed. When  the  dialog
  197. contains an additional "OK / Save" button and the user just
  198. presses  the  "Ok" button, the settings apply only  to  the
  199. action  that  the calling application is about to  perform,
  200. but they are not permanently changed. If, in this case, you
  201. want  to make your changes permanent, press the "Ok / Save"
  202. button.
  203.  
  204. The last button "DLL Setup..." allows the user to influence
  205. how  the  DLL  operates  in  general.  These  settings  are
  206. described below in the section "DLL Settings".
  207.  
  208.  
  209. DLL Settings
  210.  
  211. The  following settings that influence the behaviour of the
  212. DLL  can be made in the "DLL Setup..." dialog. Don't change
  213. them  unless  you think there is a reason to  do  so  (e.g.
  214. connection problems).
  215. Section Miscellaneous:
  216.  
  217. Debug mode             If checked, the DLL operates in
  218.                debug mode. See the section
  219.                "Troubleshooting" below for details on this
  220.                mode. Default is true.
  221. Reset connection after LPQ    If checked, the socket
  222.                connection is reset after an LPQ or LPRM
  223.                request. This was necessary for some older
  224.                versions of a few TCP/IP stacks in order to
  225.                reuse  TCP port numbers. Default is true.
  226. Linger time            If 0, the "linger" socket option for
  227.                connections is explicitly set to
  228.                SO_DONTLINGER.
  229.                If >0, the "linger" option is set to
  230.                SO_LINGER (enabled), and the number
  231.                specified determines the timeout in
  232.                seconds.
  233.                If -1, the socket's linger setting remains
  234.                the same as it was when WINSOCK.DLL created
  235.                the socket.
  236.                Default is -1 (linger setting remains
  237.                unchanged). If you have problems with
  238.                connections that sometimes work and
  239.                sometimes not (or fail every other time)
  240.                set this value to something different than
  241.                -1.
  242. Section Timeouts:
  243.  
  244. Connect timeout        Time (in seconds) after which a not
  245.                yet established connection to a server
  246.                fails. Default is 30.
  247. Send/receive timeout   Time (in seconds) after which a send
  248.                or receive operation to/from a server fails
  249.                if there is no progress.
  250. Close timeout          Time (in seconds) allowed for a
  251.                server to react on a connection closed by
  252.                the DLL (by closing the connection, too)
  253.                before the connection is reset.
  254.  
  255.  
  256.  
  257. Known problems:
  258.  
  259.    Some  WINSOCK  implementations create  problems  when  a
  260.    program   tries   to   close   a   non-blocking   socket
  261.    gracefully. The problem can be circumvented  by  setting
  262.    the  TCP  linger option for the socket connection  to  a
  263.    non-zero timeout value in the "DLL Setup..." dialog.
  264.    If  queries for a remote queue status hang after  a  few
  265.    attempts  (or every other try) make sure that  the  item
  266.    "Reset  connection  after LPQ"  in  the  "DLL  Setup..."
  267.    dialog is checked.
  268.  
  269.  
  270. Troubleshooting:
  271.  
  272. If you have problems with an application that prints by use
  273. of  this  DLL,  please don't hesitate to  contact  me.  But
  274. please  do  one  thing  before that  so  that  I  get  some
  275. information  about what is happening: Switch the  DLL  into
  276. debug  mode  in  the  "DLL  Setup..."  dialog.  After  this
  277. WLPR2.DLL  writes  a debug log to the file  C:\WLPRDEB.LST.
  278. (Note  that  you have to stop all programs using  WLPR2.DLL
  279. and  restart  them to get this effective because  this  INI
  280. entry  is  checked   at  DLL  load  time).  This  file   is
  281. overwritten  with each LPR/LPQ/LPRM request. When  you  did
  282. one  of  those  requests and you got an error,  immediately
  283. rename the above file to some other name before you execute
  284. another  request. Then mail me this file. When all problems
  285. are resolved you can disable debug mode again.
  286.  
  287.  
  288. Change Log:
  289.  
  290. Version 2.0a:
  291.    WSACleanup()  was  not called when the  WINSOCK.DLL  was
  292.    unloaded.
  293.    Default  for  the "Reset after LPQ" DLL setting  changed
  294.    to "yes".
  295.    Now  the  user  may explicitly define whether  files  in
  296.    queues  of  type  "Formatted file (f)" and  "Print  with
  297.    'pr' (p)" shall run through a CRLF->LF filter.
  298.    If    the    networking   software   (or   WSOCKAID.DLL,
  299.    respectively)  cannot  return a  username  to  WLPR2.DLL
  300.    (because   the   networking  software  does   not   have
  301.    something  like this and the user did not set  one  with
  302.    the   WSAIDCNF.CPL  Control  Panel  applet  coming  with
  303.    WSOCKAID.DLL), a default username "pcuser"  is  used  by
  304.    WLPR2.DLL.  The  user is notified of this  fact  with  a
  305.    message  box  the  first time he tries to  print.  Later
  306.    prints use this default without further notification.
  307.    Removed  a  bug which caused an LPQ request to  hang  on
  308.    some WINSOCK implementations.
  309.    All timeout parameters for a connection can now be user-
  310.    defined in the "DLL Setup..." dialog.
  311.  
  312.